home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Interactive Reference Guide / C-C++ Interactive Reference Guide.iso / c_ref / csource3 / 123_01 / ar1.doc < prev    next >
Text File  |  1985-03-11  |  8KB  |  284 lines
  1. .bp 1
  2. .in 0
  3. .he 'AR1 (1)'03/10/83'AR1 (1)'
  4. .fo ''-#-'
  5. .fi
  6. .in 7
  7. .ti -7
  8. NAME
  9. .br
  10. ar1 - archive file maintainer
  11. .sp 1
  12. .ti -7
  13. SYNOPSIS
  14. .br
  15. ar1 [-](d|p|t|u|x)[v] archive [files]
  16. .sp 1
  17. .ti -7
  18. DESCRIPTION
  19. .br
  20. AR1 collects sets of arbitrary files into one big file and
  21. maintains that file as an 'archive'.
  22. Files can be extracted from the archive, new ones can be added,
  23. old ones can be deleted or replaced by updated versions, and
  24. data about the contents can be listed.
  25.  
  26. If a minus sign ('-') is given as a file name, further file names
  27. are read from the standard input, one file name per line.
  28.  
  29. Files that are to be added to an archive must exist as
  30. files with the name given.  Files that are extracted from
  31. an archive will be put onto files with the name given.
  32. Files that are added to archives can, of course, be archive files
  33. themselves.  There is no (theoretical) limit to the number
  34. of files that can be nested this way.
  35. Thus AR1 provides the utility necessary to maintain tree-structured
  36. file directories.
  37.  
  38. AR1 is invoked by the command line
  39.  
  40. .ti +10
  41. AR1 command archname [optional filenames]
  42.  
  43. where 'command' is any one of 'dptux', optionally concatenated
  44. with 'v', specifying what operation to perform on the
  45. archive file named 'archname'.
  46. The possible commands are:
  47. .br
  48.  
  49. .in +10
  50. u - Update named archive by replacing existing files or adding new
  51. ones at end.
  52. If the 'v' option is used, file names will be printed on the
  53. standard output as files are written to the new archived file.
  54.  
  55. x - Extract named files from archive.  Put onto file of the
  56. same name.
  57. If the 'v' option is added, file names will be printed on the
  58. standard output as files are extracted.
  59.  
  60. d - Delete named files from archive.
  61. If the 'v' option is used, file names will be printed on
  62. the standard output as they are deleted from the archive.
  63.  
  64. p - Print named files on standard output.
  65. Using the 'v' option will cause the file name to precede the file.
  66.  
  67. t - Print table of archive contents.
  68. Normally, the table will contain only the file name.
  69. If the 'v' option is used, the table will also contain
  70. the file's length, type, and date and time of last change.
  71.  
  72. v - Verbose.  This command may be concatenated to any of the above
  73. commands,
  74. and will cause the archiver to print additional information,
  75. generally file names, on the standard output.
  76. Its specific action for each command has already been described.
  77. .br
  78. .in -10
  79.  
  80. The optional filenames in the command line specify individual
  81. files that may participate in the action.
  82. If no files are named, the action is done on ALL files in the archive,
  83. but if any files are explicitly named, they are the ONLY ones that
  84. take part in the action.
  85. (The 'd' command is an exception--files may be deleted only by
  86. specifying their names.)
  87. .sp 1
  88. .ti -7
  89. FILES
  90. .br
  91. Files of the form 'temp.$n$' are created and subsequently deleted for each run.
  92. .sp 1
  93. .ti -7
  94. SEE ALSO
  95. .br
  96. The Unix commands 'ar' and 'ls' in the Unix manual
  97. .br
  98. The RATFOR AR2 tool.
  99. .sp 1
  100. .ti -7
  101. DIAGNOSTICS
  102. .br
  103. archive not in proper format
  104. .br
  105. .in +10
  106. The basic problem is that archive didn't find a header
  107. line where one was expected.
  108. Typical reasons include misspelling the file name,
  109. using an existing file (not in archive format)
  110. on a creation run, and
  111. referencing an archive file that has been modified
  112. directly (say with the editor).
  113. .br
  114. .in -10
  115.  
  116. archive integrity in doubt - missing trailer
  117. .br
  118. .in +10
  119. Each file in an archive is terminated by a special line called a
  120. "trailer," which must be present.
  121. The message is caused by the lack of a trailer line when one was
  122. expected.
  123. .br
  124. .in -10
  125.  
  126. delete by name only
  127. .br
  128. .in +10
  129. For user protection, files are allowed to be deleted from an archive
  130. only by specifying each file name.
  131. .br
  132. .in -10
  133.  
  134. duplicate file name
  135. .br
  136. .in +10
  137. A file was listed more than once when calling the archiver
  138. .br
  139. .in -10
  140.  
  141. fatal errors-archive not altered
  142. .br
  143. .in +10
  144. This message is generated whenever one or more of the other
  145. errors have been detected.  An archive is never altered unless
  146. EVERYTHING has run properly.
  147. .br
  148. .in -10
  149.  
  150. too many file names
  151. .br
  152. .in +10
  153. At the present the user may call the archiver with no more than
  154. 25 files at a time.
  155. .br
  156. .in -10
  157.  
  158. usage:  ar [-](dptux)[v] archive [files]
  159. .br
  160. .in +10
  161. The command line passed to the archiver is in error.
  162. Possibly the command is wrong or the archive file name
  163. has not been given.
  164. .br
  165. .in -10
  166.  
  167. can't add 'filename'
  168. .br
  169. .in +10
  170. The file specified by 'filename' doesn't exist or can't be
  171. opened (e. g. is locked).
  172. .br
  173.  
  174. .in -10
  175. can't create 'filename'
  176. .br
  177. .in +10
  178. The archiver could not generate a local file by the name
  179. of 'filename'.  Probably the archiver's internal file
  180. buffer space has been exceeded.
  181. .br
  182.  
  183. .in -10
  184. 'filename' not in archive
  185. .br
  186. .in +10
  187. The archiver could not locate the file specified by 'filename' in
  188. the archived file.
  189. .br
  190.  
  191. .in -10
  192. .sp 1
  193. .ti -7
  194. AUTHORS
  195. .br
  196. Original code from Kernighan and Plauger's 'Software Tools',
  197. with rewrites by Allen Akin (Georgia Institute of Technology)
  198. and minor changes suggested by David Hanson (University
  199. of Arizona).
  200. Transliterated from RATFOR to BDS C by Oscar Goldman.
  201. Conversion to BDS C library by Edward K. Ream
  202. .sp 1
  203. .ti -7
  204. BUGS/DEFICIENCIES
  205. .br
  206. AR1 is quite slow with floppies, but tolerable with hard disks
  207. and especially with memory disks.
  208. One reason for its slow speed is that it ALWAYS reads the entire archive
  209. so that it can check for a proper end to the archive.
  210. Omitting this check would increase its speed.
  211.  
  212. A different approach (taken by AR2) is to have the index either as
  213. a separate file, or as part of the archive file occupying the first
  214. several records.
  215. The index would consists of the name, some
  216. statistical information and pointers into the archive file indicating
  217. the starting and ending records as well as byte addresses within these
  218. records.
  219. This would certainly speed up access and would surely increase
  220. the usefulness of the routine.
  221.  
  222. Another problem with AR1 arises because all reads and writes are
  223. by line.  For example, a constituent of an archive must end with a
  224. NEWLINE, otherwise the trailer is messed up and the 'archive integrity'
  225. is in doubt.
  226.  
  227. Line access also prevents archiving binary files.
  228. A different approach to archiving CP/M files is clearly called for.
  229. However, it is still not clear how to tell ascii files from other files.
  230.  
  231. When the update and print commands are used, the files are
  232. updated or printed
  233. in the order they appear on the
  234. archived file, NOT the order listed on
  235. the command line.
  236.  
  237. The Unix archiver allows files to be positioned in the
  238. archive, rather than simply added at the end as AR does.
  239. This is done by adding the following commands:
  240. .br
  241. .in +10
  242.  
  243. m - Move specified files to end of archive
  244.  
  245. ma posname - Move specified files to position after file 'posname'
  246.  
  247. mb posname - Move specified files to position before file 'posname'
  248.  
  249. r - Replace specified files and place at end of archive
  250.  
  251. ra posname - Replace files and place after file 'posname'
  252.  
  253. rb posname - Replace files and place before file 'posname'
  254. .br
  255. .in -10
  256.  
  257. There are some discrepancies between the Unix version of AR and
  258. this version.  Unix uses 'r'--replace instead of 'u'--update.
  259. Unix also requires the user to specify an additional command 'n'
  260. when creating a new archive.
  261. .sp 1
  262. .ti -7
  263. NOTES
  264. .br
  265. 1.  The standard wildcard matching supplied in the wildexp package can NOT
  266. be used, since wildexp expands file names by looking at files on the
  267. DISK.
  268. In general, the names of files on the DISK have nothing to do with
  269. the names of the files in the ARCHIVE.
  270. If you feel the need for wildcard matching, make the change in the
  271. file_arg() routine.
  272.  
  273. 2.  AR1 can be used to unpack the files from the Software Tools project.
  274.  
  275. 3.  Link AR1 as follows:
  276.  
  277.     clink ar1 -f dio ar1/util
  278.  
  279. 4.  At present, the getnow() routine in ar1/util.bds just prompts the
  280. console for a time stamp.
  281. The files tod.bds and date/ssi.bds show how to replace getnow()
  282. with more clever code if you have clock or calendar hardware.
  283. he files tod.bds and date/ssi.bds show how to replace getnow()
  284. with more clever code if you have clock or